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Foreword 

This Technical Specification has been produced by the 3 rd Generation Partnership Project (3 GPP). 

3GPP acknowledges the contribution of the Parlay X Web Services specifications from The Parlay Group. The Parlay 
Group is pleased to see 3 GPP acknowledge and publish the present document, and the Parlay Group looks forward to 
working with the 3 GPP community to improve future versions of the present document. 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

x the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



The present document is part 18 of a multi-part deliverable covering the 3 rd Generation Partnership Project; Technical 
Specification Group Core Network and Terminals; Open Service Access (OS A); Parlay X Web Services, as identified 
below: 
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1 Scope 

The present document is Part 18 of the Stage 3 Parlay X Web Services specification for Open Service Access (OS A). 

The OSA specifications define an architecture that enables application developers to make use of network functionality 
through an open standardized interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA are 
contained in 3GPP TS 23.198 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Device Capabilities and Configuration Web Service aspects of the interface. All 
aspects of the Device Capabilities and Configuration Web Service are defined here, these being: 

• Name spaces. 

• Sequence diagrams. 

• Data definitions. 

• Interface specification plus detailed method descriptions. 

• Fault definitions. 

• Service policies. 

• WSDL description of the interfaces. 

The present document has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and The Parlay Group. 
Maintenance of up to 3GPP Rel-8 and new OSA Stage 1, 2 and 3 work beyond Rel-9 was moved to OMA in June 2008. 



References 



The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TR 21.905: "Vocabulary for 3GPP Specifications". 

[2] 3GPP TS 22.127: "Service Requirement for the Open Services Access (OSA); Stage 1". 

[3] 3GPP TS 23.198: "Open Service Access (OSA); Stage 2". 

[4] 3GPP TS 22.101: "Service aspects; Service principles". 

[5] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes". 

NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/ . 

[6] 3GPP TS 29.199-1: "Open Service Access (OSA); Parlay X web services; Part 1: Common". 

[7] OMA Client Provisioning. See http ://www. wapforum.org/DTD/prov.dtd 
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3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the terms and definitions given in 3GPP TS 29.199-1 [6] apply. 

3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in 3GPP TS 29.199-1 [6] apply. 

4 Detailed service description 

The Parlay X Device Capabilities and Configuration Web Service will allow applications to get information about 
device capabilities and push device configuration to a device. 

4.1 Device Capabilities and 4.2 Device Configuration gives a description of each of these two possibilities. 



4.1 Device Capabilities 



An application retrieves the device capabilities of a user"s device by providing their phone number. The device 
capabilities are described by a user profile XML file, which URL is stored in the DeviceCapability structure returned 
when the capabilities are requested. In addition there is an operation to get the equipment identifier of the device. (The 
operation to get the device identifier is in a separate call, in case there is a wish to restrict this information more than the 
device capabilities.) 

In addition it is possible to set up notification for device identifier changes and receive the notifications when the device 
identifier changes. 



4.2 Device Configuration 



The application pushes the device configuration to a user"s device by providing their phone number and the 
configuration (chosen from a list of available configurations.) The application can get the list of available 
configurations for a given device and the history of the configurations previously pushed to the user"s device. 
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4.3 Application scenarios 



The Parlay X Device Capabilities and Configuration web service relies on the Parlay/OSA Terminal Capabilities SCF 
and one of the Parlay/OSA or Parlay X Messaging interfaces. In addition storage for configuration files is provided. . 
These files should respect the OMA Client Provisioning standard [7]. Usually sent to the subscriber device by SMS 
messages these files may configure settings such as WAP, MMS, Emails, etc. The following figure gives two examples 
of applications that can utilize the Device Capabilities and Configuration web service. One is a Customer Relationship 
Management Application used by an operator, the other is a Self Care Application used by the subscribers. 



Operator 



Subscriber 



Customer 

Relationship 

Management 

Application 



Self Care 
Application 



Parlay X Device Capabilities 
and Configuration 



Configuration 
storage 



Parlay/OSA Terminal 
Capabilities SCF 



Parlay (X) 
Messaging 
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5 Namespaces 

The DeviceCapabilities interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/device_capabilities/v3_0 
The DeviceCapabilitiesNotificationManager interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/device_capabilities/notification_manager/v3_0 
The DeviceCapabilitiesNotification interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/device_capabilities/notification/v3_0 
The DeviceConfiguration interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/device_capabilities/device_configuration/v3_0 
The data types are defined in the namespace: 

http://www.csapi.org/schema/parlayx/device_capabilities/v3_0 

The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in XML Schema _ 
[5]. The use of the name 'xsd' is not semantically significant. 
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Sequence diagrams 



6.1 Device Capability 



The application gets the device capabilities of a device. With the device capabilities the application can chose the right 
version of another service to make available for the user (not shown in the diagram.) 
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6.2 Device Configuration 



The first device configuration sequence diagram shows how an application for a customer service operator can utilize 
the configuration history when a customer calls in with configuration problems. The application first gets the 
configuration history, and then the customer service operator chooses to push the previous configuration to the device. 
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Another possibility is for the customer service operator to check available configurations for the customer" s device 
when the customer calls. Then the operator chooses a configuration to push to the device. 
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7 XML Schema data type definition 

7.1 ConfigurationDescription Structure 

Data structure containing the configuration ID, name, description and a link to the URL where the configuration XML 
file can be found. 



Element Name 


Element Type 


Optional 


Description 


configurationld 


xsd:string 


No 


A unique identifier for the Configuration 


name 


xsd:string 


No 


The name of the configuration. 


description 


xsd:string 


No 


The description of the configuration 


configurationReference 


xsd:anyURI 


No 


The URL where the configuration XML file can be found 



7.2 ConfigurationHistory Structure 



Data structure containing configuration (ConfigurationDescription) and a timestamp for when this configuration was 
sent to a device address. 



Element Name 


Element Type 


Optional 


Description 


configuration 


ConfigurationDescription 


No 


A Configuration 


timestamp 


xsd:dateTime 


No 


The date/time when the configuration was sent to the device 
address. 



7.3 DeviceCapabilities Structure 



Data structure containing device capabilities consisting of a device ID that uniquely identifies the device type, the name 
of the device/model, and a link to the URL where the User Agent Profile XML file can be found. 



Element Name 


Element Type 


Optional 


Description 


deviceld 


xsd:string 


No 


A unique identifier for the device type 


name 


xsd:string 


No 


The name of the device/model. 


userAgentProfileRefer 
ence 


xsd:anyURI 


No 


The URL where the User Agent Profile XML file is located 
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8 



Web Service interface definition 



8.1 Interface: DeviceCapabilities 

Request information on capabilities of a device. 

8.1 .1 Operation: getCapabilities 

This operation is intended to get the capabilities of a given device. The device is identified by its address (i.e. the phone 
number). The URI provided is for a single device, not a group URL If a group URI is provided, a fault (POL0006) will 
be returned to the application. The information returned is the Device Capabilities consisting of a unique ID for the 
device type, the name of the device/model and a link to the User Agent Profile XML file for the device. 



8.1.1.1 



Input message: getCapabilitiesRequest 



Part Name 


Part Type 


Optional 


Description 


address 


xsd:anyURI 


No 


Address of the device 



8.1.1.2 



Output message: getCapabilitiesResponse 



Part Name 


Part Type 


Optional 


Description 


result 


DeviceCapabilities 


No 


Identification of the device and link to User Agent Profile 



8.1 .1 .3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VC000 1 : Service error. 

• SVC0002: Invalid input value. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POL0001: Policy error. 

• POL0006: Groups not allowed. 
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8.1 .2 Operation: getDeviceld 



This operation is intended to get the equipment identifier (e.g. IMEI) of a given device. The device is referenced by its 
address (i.e. the phone number). The URI provided is for a single address, not a group address. If a group address is 
provided, a fault (POL0006) will be returned to the application. 



8.1.2.1 



Input message: getDeviceldRequest 



Part Name 


Part Type 


Optional 


Description 


address 


xsd:anyURI 


No 


Address of the device 



8.1.2.2 



Output message: getDeviceldResponse 



Part Name 


Part Type 


Optional 


Description 


result 


xsd:string 


No 


Equipment identifier of the 
device 



8.1.2.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VC000 1 : Service error. 

• SVC0002: Invalid input value. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POL0001: Policy error. 

• POL0006: Groups not allowed. 
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8.2 Interface: DeviceCapabilitiesNotificationManager 

Set up notifications for device changes. 

8.2.1 Operation: startNotification 

The notification pattern with correlation is used in order to correlate the notification events with the request. The 
application sets a notification trigger on equipment identifier change. In the case where the address part is a group 
address, the application is setting a notification of equipment identifier change for every device address in the group. 
Note that the reference part contains the correlator string used in subsequent messages to the notification interface. 



8.2.1.1 



Input message: startNotificationRequest 



Part Name 


Part Type 


Optional 


Description 


address 


xsd:anyURI[1 ..unbounded] 


No 


The address(es) or address group(s), for one or more 
devices that the application wants to monitor for equipment 
identifier changes. 


reference 


common:SimpleReference 


No 


Notification endpoint definition 


duration 


common:TimeMetric 


Yes 


Length of the time for which notifications occur. Do not 
specify to use default notification duration defined by service 
policy. 



8.2.1.2 



Output message: startNotification Response 



Part Name 


Part Type 


Optional 


Description 


None 









8.2.1.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VC000 1 : Service error. 

• SVC0002: Invalid input value. 

• SVC0004: No valid address(es). 

• SVC0005: Duplicate correlator. 

• SVC0006: Invalid group. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POL0001: Policy error. 

• POL0002: Privacy error. 

• POL0003: Too many addresses. 

• POL0006: Groups not allowed. 

• POL0007: Nested groups not allowed. 
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8.2.2 Operation: endNotification 



The application may end a notification using this operation. Until this operation completes, notifications may continue 
to be received by the application. 

An end of notification (device ChangeNotificationEnd) operation will not be invoked on the application for a 
notification ended using the endNotification operation. 



8.2.2.1 



Input message: endNotificationRequest 



Part Name 


Part Type 


Optional 


Description 


correlator 


xschstring 


No 


The notification the application wants to cancel. 



8.2.2.2 Output message: endNotificationResponse 



Part Name 


Part Type 


Optional 


Description 


None 









8.2.2.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VC000 1 : Service error. 

• SVC0002: Invalid input value. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POL0001: Policy error. 
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8.3 Interface: DeviceCapabilitiesNotification 

Notification interface to which device change notifications are delivered. 

8.3.1 Operation: deviceNotification 

This asynchronous operation is called by the Parlay X Device Capabilities and Configuration web service when the 
equipment identifier of a monitored device changes. 



8.3.1.1 



8.3.1.2 



Input message: deviceNotification Request 



Part Name 


Part Type 


Optional 


Description 


correlator 


xsd:string 


No 


Correlator provided in request to set up this 
notification 


address 


xsd:anyURI 


No 


The address of the device 


deviceld 


xsd:string 


No 


The new equipment identifier of the device 



Output message: deviceNotificationResponse 



Part Name 


Part Type 


Optional 


Description 


None 
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8.3.2 Operation: deviceError 



This operation is invoked on the application to indicate that the Web Service is cancelling the notification. 



8.3.2.1 



Input message: deviceErrorRequest 



Part Name 


Part Type 


Optional 


Description 


correlator 


xsd:string 


No 


Correlator provided in request to set up this notification 


address 


xsd:anyURI 


Yes 


Address of the device if the error applies to an individual 
device, or not specified if it applies to the whole 
notification. 


reason 


common:ServiceError 


No 


Reason notification is being discontinued. 



8.3.2.2 



Output message: deviceErrorResponse 



Part Name 


Part Type 


Optional 


Description 


None 









8.3.3 Operation: deviceEnd 



The notifications have ended for this correlator. This message will be delivered when the duration for notifications has 
been completed. This message will not be delivered in the case of an error ending the notifications or deliberate ending 
of the notification (using endNotification). 



8.3.3.1 



Input message: deviceEndRequest 



Part Name 


Part Type 


Optional 


Description 


correlator 


xsd:string 


No 


Correlator provided in request to set up this notification ] 



8.3.3.2 



Output message: deviceEndResponse 



Part Name 


Part Type 


Optional 


Description 


None 
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8.4 Interface: DeviceConfiguration 



Pushes configurations to a device, gets history of pushed configurations and gets available configurations for a given 
device model. 

8.4.1 Operation: pushConfiguration 

The operation enables pushing a configuration to a device. If the address part is a group address, the configuration is 
pushed to all devices in the group. 

8.4.1 .1 Input message: pushConfigurationRequest 



Part Name 


Part Type 


Optional 


Description 


address 


xsd:anyURI 


No 


Address to which the configuration is pushed 


configuration 


ConfigurationDescription 


No 


The configuration pushed to the addressed specified above. 



8.4.1 .2 Output message: pushConfigurationResponse 



Part Name 


Part Type 


Optional 


Description 


None 









8.4.1 .3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VC000 1 : Service error. 

• SVC0002: Invalid input value. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POL0001: Policy error. 
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8.4.2 Operation getConfigurationList 



Gets the list of configurations available for a given device. The configurations have to be made available in advance by 
the gateway operator. 



8.4.2.1 



Input message: getConfigurationListRequest 



Part Name 


Part Type 


Optional 


Description 


deviceld 


xsd:string 


No 


The devicelD for which compatible configurations should be returned. 



8.4.2.2 



Output message: getConfigurationListResponse 



Part Name 


Part Type 


Optional 


Description 


result 


ConfigurationDescription 
[1.. unbounded] 


No 


An array of Configuration applicable to the devicelD specified 
in the input message. 



8.4.2.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VC000 1 : Service error. 

• SVC0002: Invalid input value. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POL0001: Policy error. 

8.4.3 Operation: getConfigurationHistory 

Gets the list of configurations previously pushed to a given address. The URI provided is for a single device, not a 
group URI. If a group URI is provided, a fault (POL0006) will be returned to the application. 



8.4.3.1 



Input message: getConfigurationHistoryRequest 



Part Name 


Part Type 


Optional 


Description 


address 


xsd:anyURI 


No 


Address of the device. 



8.4.3.2 



Output message: getConfigurationHistoryResponse 



Part Name 


Part Type 


Optional 


Description 


result 


ConfigurationHistory 
[1.. unbounded] 


No 


The history of configurations previously pushed to this device 
address. 



8.4.3.3 Referenced faults 

ServiceException from 3GPP TS 29.199-1 [6]: 

• S VC000 1 : Service error. 

• SVC0002: Invalid input value. 
PolicyException from 3GPP TS 29.199-1 [6]: 

• POL0001: Policy error. 
POL0006: Groups not allowed. 
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Fault definitions 



There are no service- specific fault definitions for this service. 



10 Service policies 



Name 


Type 


Description 


MaximumNotificationAddresses 


xsd:int 


Maximum number of addresses for which a notification 
can be set up 


MaximumNotificationDuration 


common:TimeMetric 


Maximum amount of time for which a notification may be 
set up. 


GroupSupport 


xsd:boolean 


Indicates whether group URIs may be used 


NestedGroupSupport 


xsd:boolean 


Indicates whether nested groups are supported in group 
definitions 
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Annex A (normative): 

WSDL for Device Capabilities and Configuration 

The document/literal WSDL representation of this interface specification is compliant to 3GPP TS 29.199-1 [6] and is 
contained in text files (contained in archive 29199-18-800-doclit.zip) which accompanies the present document. 
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Annex B (informative): 

Description of Parlay X Web Services Part 18: Device 

Capabilities and Configuration for 3GPP2 cdma2000 

networks 

This annex is intended to define the OSA Parlay X Web Services Stage 3 interface definitions and it provides the 
complete OSA specifications. It is an extension of OSA Parlay X Web Services specifications capabilities to enable 
operation in cdma2000 systems environment. They are in alignment with 3GPP2 Stage 1 requirements and Stage 2 
architecture defined in: 

[1] 3GPP2 X.S001 1-D: 'cdma2000 Wireless IP Network Standard ", Version 1.1 

[2] 3GPP2 S.R0037-0: "IP Network Architecture Model for cdma2000 Spread Spectrum Systems", 

Version 3.0 

[3] 3GPP2 X.S0013-A: "All-IP Core Network Multimedia Domain" 

These requirements are expressed as additions to and/or exclusions from the 3GPP specification. 

The information given here is to be used by developers in 3GPP2 cdma2000 network architecture to interpret the 3 GPP 

OSA specifications. 



B.1 General Exceptions 



The terms 3GPP and UMTS are not applicable for the cdma2000 family of standards. Nevertheless these terms are used 
(3GPP TR 21.905) mostly in the broader sense of "3G Wireless System". If not stated otherwise there are no additions 
or exclusions required. 

CAMEL mappings are not applicable for cdma2000 systems. 



B.2 Specific Exceptions 
B.2.1 Clause 1: Scope 

There are no additions or exclusions. 

B.2.2 Clause 2: References 

There are no additions or exclusions. 

B.2. 3 Clause 3: Definitions and abbreviations 

There are no additions or exclusions. 

B.2. 4 Clause 4: Detailed service description 

There are no additions or exclusions. 

B.2. 5 Clause 5: Namespaces 

There are no additions or exclusions. 
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B.2.6 Clause 6: Sequence diagrams 

There are no additions or exclusions. 

B.2.7 Clause 7: XML Schema data type definition 

There are no additions or exclusions. 

B.2.8 Clause 8: Web Service interface definition 

There are no additions or exclusions. 

B.2.9 Clause 9: Fault definitions 

There are no additions or exclusions. 

B.2.10 Clause 10: Service policies 

There are no additions or exclusions. 

B.2.1 1 Annex A (normative): WSDL for Device Capabilities and 
Configuration 

There are no additions or exclusions. 
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Annex C (informative): 
Change history 



Change history 


Date 


TSG# 


TSG Doc. 


CR 


Rev 


Subject/Comment 


Cat 


Old 


New 


Mar 2007 


CT 35 


CP-070052 


-- 


-- 


Submitted to TSG CT#35 for Information. 


-- 


1.0.0 




May 2007 


CT_36 


CP-070348 






Updates and name change (Device Management to Device Capabilities 

and Configuration.) 

Submitted to TSG CT#36 for Approval. 




1.0.0 


2.0.0 


Jun 2007 


— 


— 


— 


— 


Added missing WSDL code attachment. Updated based on 29199-18- 
200JsrComments_SUPPLEMENT 


— 


2.0.0 


2.0.1 


Jun 2007 


CT 36 


-- 


-- 


-- 


TSG CT#36 Approved 


- 


2.0.1 


7.0.0 


Dec 2008 


CT_42 


-- 


-- 


-- 


Upgraded unchanged from Rel-7 


- 


7.0.0 


8.0.0 
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